<!DOCTYPE html>
<html lang="en-US">
    <head>
        <title>Pod::HTML2Pod - translate HTML into POD - metacpan.org</title>
        <link rel="preload" as="fetch" href="https://metacpan.org/account/login_status" crossorigin="anonymous" />
        <link href="https://metacpan.org/_assets/b8ccceeed47a0652049703d99326a9cea4933443.css" rel="stylesheet" type="text/css">
        <script src="https://metacpan.org/_assets/6bfedafe2d7caa915b7d84f61b45936818e3242e.js" type="text/javascript" defer></script>
        <link rel="alternate" type="application/rss+xml" title="Recent CPAN Uploads of Pod-HTML2Pod - MetaCPAN" href="https://metacpan.org/dist/Pod-HTML2Pod/releases.rss" />
        <link rel="canonical" href="./Pod::HTML2Pod.html" />
        <meta name="description" content="translate HTML into POD" />
        <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=5">
        <link rel="shortcut icon" href="https://metacpan.org/static/icons/favicon.ico">
        <link rel="apple-touch-icon" sizes="152x152" href="https://metacpan.org/static/icons/apple-touch-icon.png">
        <link rel="search" href="https://metacpan.org/static/opensearch.xml" type="application/opensearchdescription+xml" title="MetaCPAN">
        <script>
          (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
          (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
          m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
          })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

          (function(skey, ga_id){
            ga('create', ga_id, {
              siteSpeedSampleRate : 100,
              storage             : 'none',
              clientId            : localStorage.getItem(skey)
            });
            ga(function(tracker) {
              localStorage.setItem(skey, tracker.get('clientId'));
            });
            ga('send', 'pageview');
          })('ga:clientId', 'UA-27829474-1');
        </script>
<meta name="twitter:card"        content="summary" />
<meta name="twitter:url"         content="https://metacpan.org/pod/Pod::HTML2Pod" />
<meta name="twitter:title"       content="Pod::HTML2Pod" />
<meta name="twitter:description" content="translate HTML into POD" />
<meta name="twitter:site"        content="metacpan" />
    </head>
    <body>
        <nav class="navbar navbar-default" role="navigation">
            <div class="header-logo-large hidden-xs">
              <a href="https://metacpan.org/" tabindex="0">
                <svg class="logo" aria-label="MetaCPAN">
                  <use class="logo" href="/static/images/metacpan-logo.svg#logo" />
                </svg>
              </a>
            </div>
            <div class="header-logo-icon visible-xs">
              <a href="https://metacpan.org/">
                <svg class="logo" aria-label="MetaCPAN">
                  <use class="logo" href="/static/images/metacpan-logo.svg#dots" />
                </svg>
              </a>
            </div>
            <ul class="nav navbar-nav menu-items hidden-xs hidden-sm">
              <li><a href="https://metacpan.org/about">About</a></li>
              <li><a href="https://metacpan.org/about/sponsors">Sponsor</a></li>
              <li><a href="https://grep.metacpan.org/">grep::cpan</a></li>
              <li><a href="https://metacpan.org/recent">Recent</a></li>
              <li><a href="https://metacpan.org/about/faq">FAQ</a></li>
              <li><a href="https://metacpan.org/tools">Tools</a></li>
              <li><a href="https://fastapi.metacpan.org/">API</a></li>
            </ul>
            <ul class="nav navbar-nav navbar-right">
                <button type="button" class="searchbar-btn visible-xs visible-sm">
                    <i class="fa fa-search button-fa-icon"></i>
                </button>
                <form action="https://metacpan.org/search" class="searchbar-form visible-md visible-lg search-form form-horizontal">
                   <input type="hidden" name="size" id="metacpan_search-size" value="20">
                  <div class="form-group">
                      <div class="search-group">
                        <i class="fa fa-search"></i>
                        <input type="text" name="q" placeholder="Search the CPAN" size="41" autocorrect="off" autocapitalize="off" spellcheck="false" id="metacpan_search-input" class="form-control" value="">
                      </div>
                  </div>
                </form>
                    <li class="icon-slidepanel visible-xs visible-sm">
                      <button data-toggle="slidepanel" data-target=".slidepanel">
                        <span class="button-fa-icon">
                          <i class="fa fa-bars slidepanel-open"></i>
                          <i class="fa fa-times slidepanel-close"></i>
                        </span>
                      </button>
                    </li>
                <form action="https://metacpan.org/account/logout" method="POST" id="metacpan-logout"></form>
                <li class="dropdown logged_in" style="display: none;">
                    <button type="button" class="dropdown-toggle" data-toggle="dropdown">
                      <i class="fa fa-user button-fa-icon logged-in-icon" aria-hidden="true"></i>
                      <i class="fas fa-chevron-down"></i>
                    </button>
                    <ul class="dropdown-menu">
                        <li><a href="https://metacpan.org/account/identities">Identities</a></li>
                        <li><a href="https://metacpan.org/account/profile">Profile</a></li>
                        <li><a href="https://metacpan.org/account/favorite/list">Favorites</a></li>
                        <li>
                            <a href="./Pod::HTML2Pod.html#" type="button" onclick="$('#metacpan-logout').submit(); return false">
                              Logout
                            </a>
                        </li>
                    </ul>
                </li>
                <li class="dropdown logged_out" style="display: none;">
                    <button type="button" class="dropdown-toggle" data-toggle="dropdown">
                      <i class="fa fa-user button-fa-icon" aria-hidden="true"></i>
                      <i class="fas fa-chevron-down"></i>
                    </button>
                    <ul class="dropdown-menu">
                        <li>
                            <a href="https://metacpan.org/login/github">
                                <i class="fab fa-github fa-fw"></i>
                                GitHub
                            </a>
                        </li>
                        <li>
                            <a href="https://metacpan.org/login/twitter">
                                <i class="fab fa-twitter fa-fw"></i>
                                Twitter
                            </a>
                        </li>
                        <li>
                            <a href="https://metacpan.org/login/google">
                                <i class="fab fa-google fa-fw"></i>
                                Google
                            </a>
                        </li>
                    </ul>
                </li>
                <li class="dropdown logged_placeholder">
                    <button>
                      <i class="fa fa-user button-fa-icon" aria-hidden="true"></i>
                    </button>
                </li>
            </ul>
        </nav>
        <div class="page-content ">
          <!--
          <div class="top-notify-banner">
            <i class="fas fa-info-circle"></i>
          </div>
          -->
          <nav class="sidebar">
            <div class="slidepanel">
              <ul class="nav-list ">
    <li class="nav-header no-margin-top">
      <div class="ttip" data-toggle="tooltip" data-placement="bottom" title="The date that this version of Pod-HTML2Pod was released.">
      <span class="relatize">30 Dec 2004 07:49:03 UTC</span>
    </li>
  <li>
    Distribution: <a href="https://metacpan.org/dist/Pod-HTML2Pod">Pod-HTML2Pod</a>
  </li>
  <li>
    Module version: 4.05
  </li>
  <li>
    <a data-keyboard-shortcut="g s" href="https://metacpan.org/dist/Pod-HTML2Pod/source/lib/Pod/HTML2Pod.pm">Source</a>
    (<a href="https://metacpan.org/dist/Pod-HTML2Pod/source/lib/Pod/HTML2Pod.pm?raw=1">raw</a>)
  </li>
  <li>
    <a data-keyboard-shortcut="g b" href="https://metacpan.org/dist/Pod-HTML2Pod/source/lib/Pod">Browse</a>
    (<a href="https://metacpan.org/dist/Pod-HTML2Pod/source/lib/Pod?raw=1">raw</a>)
  </li>
    <li>
      <a data-keyboard-shortcut="g c" href="https://metacpan.org/dist/Pod-HTML2Pod/changes">Changes</a>
    </li>
    <li>
      <a class="nopopup" href="https://metacpan.org/dist/Pod-HTML2Pod/contribute">How to Contribute</a>
    </li>
    <li>
      <a rel="noopener nofollow" data-keyboard-shortcut="g i" href="https://rt.cpan.org/Public/Dist/Display.html?Name=Pod-HTML2Pod">Issues</a>
      (1)
    </li>
    <li>
      <a rel="noopener nofollow" href="http://matrix.cpantesters.org/?dist=Pod-HTML2Pod+4.05" title="Matrix">Testers</a>
        <span title="(pass / fail / na)">(<a rel="noopener nofollow" href="https://www.cpantesters.org/distro/P/Pod-HTML2Pod.html?oncpan=1&amp;distmat=1&amp;version=4.05&amp;grade=2" style="color: #090">906</a> / <a rel="noopener nofollow" href="https://www.cpantesters.org/distro/P/Pod-HTML2Pod.html?oncpan=1&amp;distmat=1&amp;version=4.05&amp;grade=3" style="color: #900">0</a> / <a rel="noopener nofollow" href="https://www.cpantesters.org/distro/P/Pod-HTML2Pod.html?oncpan=1&amp;distmat=1&amp;version=4.05&amp;grade=4">0</a>)</span>
    </li>
    <li>
      <a rel="noopener nofollow" href="http://cpants.cpanauthors.org/release/SBURKE/Pod-HTML2Pod-4.05">Kwalitee</a>
    </li>
    <li>
      <div class="ttip" data-toggle="tooltip" data-placement="bottom" title="The # people with an indexing permission on Pod-HTML2Pod who have released something to CPAN in the last 2 years (i.e. the # people likely able to release critical fixes in a timely manner)">
      Bus factor: 0
      </div>
    </li>
    <li>
      <a rel="noopener nofollow" href="http://cpancover.com/latest/Pod-HTML2Pod-4.05/index.html">45.73% Coverage </a>
    </li>
    <li>
      License: unknown
    </li>
    <li class="nav-header">Activity</li>
    <li>
<div class="activity-graph">
    <img src="https://metacpan.org/dist/Pod-HTML2Pod/activity.svg?res=month" />
    <div class="comment">24 month</div>
</div>
    </li>
    <li class="nav-header">Tools</li>
    <li>
      <a itemprop="downloadUrl" href="https://cpan.metacpan.org/authors/id/S/SB/SBURKE/Pod-HTML2Pod-4.05.tar.gz">
      Download (<span itemprop="fileSize">18.39KB</span>)</a>
    </li>
    <li>
      <a href="https://explorer.metacpan.org/?url=%2Fmodule%2FSBURKE%2FPod-HTML2Pod-4.05%2Flib%2FPod%2FHTML2Pod.pm">
        MetaCPAN Explorer
      </a>
    </li>
    <li>
      <a href="https://metacpan.org/dist/Pod-HTML2Pod/permissions">
        Permissions
      </a>
    </li>
    <li>
      <a href="https://metacpan.org/dist/Pod-HTML2Pod/releases.rss">
        Subscribe to distribution
      </a>
    </li>
    <li>
      <button class="btn btn-link" data-toggle="modal" data-target="#metacpan_install-instructions-dialog">
        Install Instructions
      </button>
    </li>
    <li>
      <form action="https://metacpan.org/search">
        <input type="hidden" name="q" value="dist:Pod-HTML2Pod">
        <input type="search" name="q" placeholder="Search distribution" class="form-control tool-bar-form">
        <input type="submit" style="display: none">
      </form>
    </li>
    <li>
      <form action="https://grep.metacpan.org/search">
        <input type="hidden" name="qd" value="Pod-HTML2Pod">
        <input type="hidden" name="source" value="metacpan">
        <input type="search" name="q" placeholder="grep distribution" class="form-control tool-bar-form">
        <input type="submit" style="display: none">
     </form>
    </li>
    <li class="version-jump">
<select onchange="document.location.href=&#39;/release/&#39;+this.value+&#39;/view/lib/Pod/HTML2Pod.pm&#39;" class="form-control tool-bar-form">
  <option disabled selected>Jump to version</option>
<option
  disabled
  value="SBURKE/Pod-HTML2Pod-4.05"
>4.05
  (SBURKE on 2004-12-30)</option>
<optgroup label="BackPAN">'
<option
  
  value="SBURKE/Pod-HTML2Pod-4.04"
>4.04
  (SBURKE on 2000-10-04)</option>
<option
  
  value="SBURKE/Pod-HTML2Pod-4.03"
>4.03
  (SBURKE on 2000-10-04)</option>
</optgroup>
</select>
    </li>
    <li class="version-diff">
<select onchange="document.location.href='/release/SBURKE/Pod-HTML2Pod-4.05/diff/' + encodeURIComponent(this.value) + '/lib/Pod/HTML2Pod.pm'
" class="form-control tool-bar-form">
  <option disabled selected>Diff with version</option>
<option
  disabled
  value="SBURKE/Pod-HTML2Pod-4.05"
>4.05
  (SBURKE on 2004-12-30)</option>
<optgroup label="BackPAN">'
<option
  
  value="SBURKE/Pod-HTML2Pod-4.04"
>4.04
  (SBURKE on 2000-10-04)</option>
<option
  
  value="SBURKE/Pod-HTML2Pod-4.03"
>4.03
  (SBURKE on 2000-10-04)</option>
</optgroup>
</select>
    </li>

    <li>
<ul class="dependencies">
  <li class="nav-header">Dependencies</li>
  <li><a href="https://metacpan.org/pod/Carp" title="Carp" class="ellipsis">Carp</a></li>
  <li><a href="https://metacpan.org/pod/HTML::Element" title="HTML::Element" class="ellipsis">HTML::Element</a></li>
  <li><a href="./HTML::Entities.html" title="HTML::Entities" class="ellipsis">HTML::Entities</a></li>
  <li><a href="https://metacpan.org/pod/HTML::Tagset" title="HTML::Tagset" class="ellipsis">HTML::Tagset</a></li>
  <li><a href="./HTML::TreeBuilder.html" title="HTML::TreeBuilder" class="ellipsis">HTML::TreeBuilder</a></li>
  <li><a href="https://metacpan.org/pod/UNIVERSAL" title="UNIVERSAL" class="ellipsis">UNIVERSAL</a></li>
  <li><a href="https://metacpan.org/pod/integer" title="integer" class="ellipsis">integer</a></li>
  <li><i class="ttip" title="dynamic_config enabled">and possibly others</i></li>
  <li>
    <hr>
  </li>
  <li>
    <a href="https://metacpan.org/module/Pod::HTML2Pod/requires">Reverse dependencies</a>
  </li>
  <li>
    <a href="http://deps.cpantesters.org/?module=Pod%3A%3AHTML2Pod">CPAN Testers List</a>
  </li>
  <li>
    <a href="https://cpandeps.grinnz.com/?dist=Pod-HTML2Pod">Dependency graph</a>
  </li>
</ul>
    </li>
    <li class="nav-header">Permalinks</li>
    <li>
      <a href="https://metacpan.org/release/SBURKE/Pod-HTML2Pod-4.05/view/lib/Pod/HTML2Pod.pm">This version</a>
    </li>
    <li>
      <a href="./Pod::HTML2Pod.html">Latest version</a>
    </li>
    <li>
<div class="plussers">
<div class="nav-header">++ed by:</div>
<div>
    1 non-PAUSE user
</div>
</div>
    </li>
    <li>
    </li>
              </ul>
            </div>
          </nav>
          <div class="content-navigation">
<div class="breadcrumbs">
  <span>
    <a data-keyboard-shortcut="g a" rel="author" href="https://metacpan.org/author/SBURKE" class="author-name">Sean M. Burke</a>
  </span>
  <span>&nbsp;/&nbsp;</span>
  <div class="release dist-release status-latest maturity-released">
    <span class="dropdown"><b class="caret"></b></span>
<select onchange="document.location.href=&#39;/release/&#39;+this.value+&#39;/view/lib/Pod/HTML2Pod.pm&#39;" class="">
<option
  selected
  value="SBURKE/Pod-HTML2Pod-4.05"
>4.05
  (SBURKE on 2004-12-30)</option>
<optgroup label="BackPAN">'
<option
  
  value="SBURKE/Pod-HTML2Pod-4.04"
>4.04
  (SBURKE on 2000-10-04)</option>
<option
  
  value="SBURKE/Pod-HTML2Pod-4.03"
>4.03
  (SBURKE on 2000-10-04)</option>
</optgroup>
</select>
    <a data-keyboard-shortcut="g d" class="release-name" href="https://metacpan.org/dist/Pod-HTML2Pod">Pod-HTML2Pod-4.05</a>
  </div>
<span class="river-gauge-gauge">
  <svg width="24px"
       height="15px"
       version="1.1"
       xmlns="http://www.w3.org/2000/svg"
       xmlns:xlink="http://www.w3.org/1999/xlink">

    <g>
      <title>        River stage zero &#10;
          No dependents
      </title>

      <rect x="0"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="5"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="10"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="15"  y="0" width="4" height="15" fill="#e4e2e2" />
      <rect x="20"  y="0" width="4" height="15" fill="#e4e2e2" />
    </g>
  </svg>

</span>
<div id="Pod-HTML2Pod-fav" class="logged_in">
<form action="https://metacpan.org/account/favorite/add" style="display: inline" onsubmit="return favDistribution(this)">
    <input type="hidden" name="remove" value="0">
    <input type="hidden" name="release" value="Pod-HTML2Pod-4.05">
    <input type="hidden" name="author" value="SBURKE">
    <input type="hidden" name="distribution" value="Pod-HTML2Pod">
    <button type="submit" class="favorite highlight"><span>1</span> ++</button>
</form>
</div>
<div class="logged_out">
<a href="./Pod::HTML2Pod.html" onclick="alert('Please sign in to add favorites'); return false" class="favorite highlight">
<span>1</span> ++</a>
</div>
   / <span>Pod::HTML2Pod</span>
</div>
          </div>
          <main class="content">


<nav class="toc">
  <div class="toc-header"><strong>Contents</strong></div>
<ul>
  <li><a href="./Pod::HTML2Pod.html#NAME">NAME</a></li>
  <li><a href="./Pod::HTML2Pod.html#SYNOPSIS">SYNOPSIS</a></li>
  <li><a href="./Pod::HTML2Pod.html#DESCRIPTION">DESCRIPTION</a></li>
  <li><a href="./Pod::HTML2Pod.html#FUNCTIONS">FUNCTIONS</a></li>
  <li><a href="./Pod::HTML2Pod.html#GUIDELINES">GUIDELINES</a></li>
  <li><a href="./Pod::HTML2Pod.html#BUG-REPORTS">BUG REPORTS</a></li>
  <li><a href="./Pod::HTML2Pod.html#BUGS-AND-CAVEATS">BUGS AND CAVEATS</a></li>
  <li><a href="./Pod::HTML2Pod.html#SEE-ALSO">SEE ALSO</a></li>
  <li><a href="./Pod::HTML2Pod.html#COPYRIGHT">COPYRIGHT</a></li>
  <li><a href="./Pod::HTML2Pod.html#AUTHOR">AUTHOR</a></li>
</ul></nav>
<div class="pod anchors">
<h1 id="NAME">NAME</h1>

<p>Pod::HTML2Pod -- translate HTML into POD</p>

<h1 id="SYNOPSIS">SYNOPSIS</h1>

<pre><code>  # Use the program &#39;html2pod&#39; that comes in this dist, or:
  use Pod::HTML2Pod;
  print Pod::HTML2Pod::convert(
    &#39;file&#39; =&gt; &#39;my_stuff.html&#39;,  # input file
    &#39;a_href&#39; =&gt; 1,  # try converting links
  );</code></pre>

<h1 id="DESCRIPTION">DESCRIPTION</h1>

<p>Larry Wall once said (1999-08-27, on the <code>pod-people</code> list, I do believe): &quot;The whole point of pod is to get people to document stuff they wouldn&#39;t document in any other form.&quot;</p>

<p>To that end, I wrote this module so that people who are unpracticed with POD but in a hurry to simply document their programs or modules, could write their documentation in simple HTML, and convert that to POD. That&#39;s what this module does.</p>

<p>Specifically, this module bends over backwards to try to turn even vaguely plausable HTML into POD -- and when in doubt, it simply ignores things that it doesn&#39;t know about, or can&#39;t render.</p>

<h1 id="FUNCTIONS">FUNCTIONS</h1>

<p>This module provides one documented function, which it does not export:</p>

<dl>

<dt id="Pod::HTML2Pod::convert(-...options...-)"><a id="Pod"></a><a id="Pod::HTML2Pod::convert--...options"></a>Pod::HTML2Pod::convert( ...options... )</dt>
<dd>

</dd>
</dl>

<p>This returns a single scalar value containing the converted POD text, with some comments after the end.</p>

<p>This function takes options:</p>

<dl>

<dt id="&#39;file&#39;-=&gt;-FILENAME,"><a id="file----FILENAME"></a>&#39;file&#39; =&gt; FILENAME,</dt>
<dd>

<p>Specifies that the HTML code is to be read from the filename given.</p>

</dd>
<dt id="&#39;handle&#39;-=&gt;-*HANDLE,"><a id="handle-----HANDLE"></a>&#39;handle&#39; =&gt; *HANDLE,</dt>
<dd>

<p>Specifies that the HTML code is to be read from the open filehandle given (e.g., <code>$fh_obj</code>, <code>*HANDLE</code>, <code>*HANDLE{IO}</code>, etc.) If you specify this, but fail to specify an actual handle object, inscrutible errors may result.</p>

</dd>
<dt id="&#39;content&#39;-=&gt;-STRING,"><a id="content----STRING"></a>&#39;content&#39; =&gt; STRING,</dt>
<dd>

<p>Specifies that the HTML code is in the string given. (Alternately, pass a reference to the scalar: <code>&#39;content&#39; =&gt; \$stuff</code>.)</p>

</dd>
<dt id="&#39;tree&#39;-=&gt;-OBJ,"><a id="tree----OBJ"></a>&#39;tree&#39; =&gt; OBJ,</dt>
<dd>

<p>Specifies that the HTML document is contained in the given HTML::TreeBuilder object (or HTML::Element object, at least).</p>

</dd>
<dt id="&#39;a_name&#39;-=&gt;-BOOLEAN,"><a id="a_name----BOOLEAN"></a>&#39;a_name&#39; =&gt; BOOLEAN,</dt>
<dd>

<p>Specifies whether you want to try converting <code>&lt;a name=&quot;...&quot;&gt;</code> elements. By default this is off -- i.e., such elements are ignored.</p>

</dd>
<dt id="&#39;a_href&#39;-=&gt;-BOOLEAN,"><a id="a_href----BOOLEAN"></a>&#39;a_href&#39; =&gt; BOOLEAN,</dt>
<dd>

<p>Specifies whether you want to try converting <code>&lt;a href=&quot;...&quot;&gt;</code> elements. By default this is off -- i.e., such elements are ignored. If on, bear in mind that relative URLs cannot be properly converted to POD -- any relative URLs will be complained about in comments after the end of the document. Normal absolute URLs will be treated as best they can be. Note that URLs beginning &quot;pod:...&quot; will be turned into POD links to whatever follows; that is, &quot;pod:Getopt::Std&quot; is turned into <code>L&lt;Getopt::Std&gt;</code></p>

</dd>
<dt id="&#39;debug&#39;-=&gt;-INTEGER,"><a id="debug----INTEGER"></a>&#39;debug&#39; =&gt; INTEGER,</dt>
<dd>

<p>Puts Pod::HTML2Pod into verbose debug mode for the duration of processing this this HTML document. INTEGER can be 0 for no debug output, 1 for a moderate amount that will cause the HTML syntax tree to be be dumped at the start of the conversion, and 2 for that plus a dump of the intermediate POD doctree, plus a few more inscrutible diagnostic messages. Looking at the trees dumped might be helpful in making sense of error messages that refer to a particular node in the parse tree.</p>

</dd>
<dt id=""><a id="pod"></a></dt>
<dd>

</dd>
</dl>

<h1 id="GUIDELINES">GUIDELINES</h1>

<p>Don&#39;t write crappy HTML and expect this module to understand it.</p>

<p>Don&#39;t take the output of <code>pod2html</code> and feed it to this, just because you think it&#39;d be neat to try it. You&#39;ll just learn really unpleasant things about <code>Pod::Html</code> -- and that&#39;s fine if that means you&#39;ll use it to improve <code>Pod::Html</code>, but it&#39;s rather the long way around.</p>

<p>However, <i>do</i> use this module to convert simple HTML into POD, bearing in mind these simple truths:</p>

<p>POD can&#39;t do tables, images, forms, imagemaps, layers, CSS, embedded Java applets or any other kind of object, FONT, or BLINK. So don&#39;t try to do any of these things.</p>

<p>Use <code>&lt;h1&gt;</code> and <code>&lt;h2&gt;</code> for headings.</p>

<p>If you want to have a block of literal example code, put it in a <code>&lt;pre&gt;</code>.</p>

<p>Keep things simple.</p>

<p>Remember: Just because it comes <i>out</i> of Pod::HTML2Pod doesn&#39;t mean it&#39;s happy normal pod. You can do lots of things in HTML that will produce POD that is strange but technically legal (like having huge and complex content in a <code>&lt;h1&gt;</code>/<code>=head1</code>) but that will make perldoc scream bloody murder about nroff macros stretched past their limit.</p>

<p>Try to avoid using a WYSIWYG HTML editor, as they often produce scary source. Ditto for taking selecting &quot;Save as... HTML&quot; in your word processor. You can always try it, but look at the HTML to survey the damage before you try converting it to POD.</p>

<p>Always look at the POD that&#39;s been output by HTML2Pod -- never just blindly include it.</p>

<p>Consider starting from this template:</p>

<pre><code>  &lt;html&gt;
  &lt;head&gt;
   &lt;title&gt;Things::Stuff&lt;/title&gt;
   &lt;!-- html2pod ignores everything outside the body anyway --&gt;
  &lt;/head&gt;
  &lt;body&gt;
  &lt;h1&gt;NAME&lt;/h1&gt;
  
  Things::Stuff -- does some things with stuff
  
  &lt;h1&gt;SYNOPSIS&lt;/h1&gt;
  &lt;!-- example code --&gt;
  &lt;pre&gt;
    use HTML::Stuff;
    do some more stuff;
    la la la la la;
    oogah;
  &lt;/pre&gt;
  
  &lt;h1&gt;DESCRIPTION&lt;/h1&gt;
  
  This module does things with stuff.  It exports these functions:
  
  &lt;dl&gt;
  &lt;dt&gt;&lt;code&gt;thingify( ... )&lt;/code&gt;
  &lt;dd&gt;This function takes stuff, and returns their value as things.
  
  &lt;dt&gt;&lt;code&gt;destuffulate( ... )&lt;/code&gt;
  &lt;dd&gt;This function returns the things, from stuff.
   &lt;p&gt;It will throw a fatal exception if applied to things.
   &lt;br&gt;So don&#39;t do that.
  
  &lt;dt&gt;&lt;code&gt;enthinction( ... )&lt;/code&gt;
  &lt;dd&gt;This is where I run out of ways to make up silly sentences
   involving &quot;thing&quot; and &quot;stuff&quot;.  Mostly.
  
  &lt;/dl&gt;
  
  &lt;h2&gt;Caveats and WYA&#39;s&lt;/h2&gt;
  
  Things to be wary of:
  
  &lt;ul&gt;
  &lt;li&gt;The things.
  &lt;li&gt;And the stuff
   &lt;p&gt;Don&#39;t forget about that stuff.  Gotta keep an eye on that.
  &lt;/ul&gt;
  
  &lt;h1&gt;BUGS&lt;/h1&gt;
  
  Stuff is hard.
  
  &lt;h1&gt;SEE ALSO&lt;/h1&gt;
  
  &lt;a href=&quot;pod:Class::Classless&quot;&gt;Class::Classless&lt;/a&gt;,
  &lt;a href=&quot;pod:strict&quot;&gt;strict&lt;/a&gt;,
  &lt;a href=&quot;pod:Lingua::EN::Numbers::Ordinate&quot;
   &gt;Lingua::EN::Numbers::Ordinate&lt;/a&gt;,
  &lt;a href=&quot;pod:perlvar&quot;&gt;perlvar&lt;/a&gt;,
  
  &lt;!-- I use the secret-sauce &#39;pod:&#39; scheme as a back door for making
   simple cross-references to POD man pages --&gt;
  
  &lt;h1&gt;COPYRIGHT&lt;/h1&gt;
  
  Copyright 2000, Joey Jo-Jo Jr. Shabadoo.
  
  &lt;!-- just one suggested phrasing for the license... --&gt;
  &lt;p&gt;This library is free software; you can redistribute it and/or modify
  it under the same terms as Perl itself.
  
  &lt;h1&gt;AUTHOR&lt;/h1&gt;
  Joey Jo-Jo Jr. Shabadoo, &lt;code&gt;jojojo@shabadoo.int&lt;/code&gt;
  &lt;/body&gt;
  &lt;/html&gt;</code></pre>

<h1 id="BUG-REPORTS"><a id="BUG"></a>BUG REPORTS</h1>

<p>If you do find a case where this converter misinterprets what you consider straightforward HTML (which you should really really have run thru an HTML syntax checker, by the way!), report it to me as a bug, at <code>sburke@cpan.org</code>.</p>

<p>Be sure to include the entire document that causes the error -- then specify exactly what you consider the error to be.</p>

<h1 id="BUGS-AND-CAVEATS"><a id="BUGS"></a>BUGS AND CAVEATS</h1>

<p>* Doesn&#39;t try to turn &quot;smart quotes&quot; characters into simple &quot; and &#39;. Maybe should?</p>

<p>* Fails to turn</p>

<pre><code>  foo thing&amp;nbsp;bar&amp;nbsp;baz quux</code></pre>

<p>into</p>

<pre><code>  foo S&lt;thing bar baz&gt; quux</code></pre>

<p>I.e., currently just turns <code>&amp;nbsp;</code>&#39;s into normal spaces.</p>

<p>* Numeric entities (<code>E&lt;num&gt;</code>) are used when necessary -- but these are not understood by some older POD converters.</p>

<p>* No HTML that you provide will turn into <code>F&lt;...&gt;</code></p>

<p>* Currently maps</p>

<pre><code>  &lt;A HREF=&quot;foo&quot;&gt;bar&lt;/A&gt;</code></pre>

<p>to</p>

<pre><code>  X&lt;foo&gt;bar</code></pre>

<p>but is this correct?</p>

<h1 id="SEE-ALSO"><a id="SEE"></a>SEE ALSO</h1>

<p><a href="https://metacpan.org/pod/perlpod">perlpod</a>, <a href="https://metacpan.org/pod/Pod::Html">Pod::Html</a>, <a href="./HTML::TreeBuilder.html">HTML::TreeBuilder</a></p>

<p>And HTML Tidy, at <code>http://www.w3.org/People/Raggett/tidy/</code></p>

<h1 id="COPYRIGHT">COPYRIGHT</h1>

<p>Copyright (c) 2000 Sean M. Burke. All rights reserved.</p>

<p>This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.</p>

<h1 id="AUTHOR">AUTHOR</h1>

<p>Sean M. Burke <code>sburke@cpan.org</code></p>

<div class="pod-errors"><p>1 POD Error</p><div class="pod-errors-detail"><p>The following errors were encountered while parsing the POD:</p><dl><dt>Around line 113:</dt><dd><p>Expected text after =item, not a bullet</p></dd></dl></div></div></div>

<div id="metacpan_install-instructions-dialog" class="modal fade">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button>
        <h4 class="modal-title">Module Install Instructions</h4>
      </div>
      <div class="modal-body">
        <p>To install Pod::HTML2Pod, copy and paste the appropriate command in to your terminal.</p>
        <p><a href="https://metacpan.org/dist/App-cpanminus/view/bin/cpanm">cpanm</a></p>
        <pre><code>cpanm Pod::HTML2Pod</code></pre>
        <p><a href="https://metacpan.org/pod/CPAN">CPAN shell</a></p>
        <pre><code>perl -MCPAN -e shell
install Pod::HTML2Pod</code></pre>
        <p>For more information on module installation, please visit <a href="https://www.cpan.org/modules/INSTALL.html">the detailed CPAN module installation guide</a>.</p>
      </div>
      <div class="modal-footer">
        <a href="./Pod::HTML2Pod.html#" data-dismiss="modal" class="btn">Close</a>
      </div>
    </div>
  </div>
</div>
          </main>
          <div class="content-pagination">
          </div>
        </div>
        <footer class="footer">
          <div class="footer-container">
            <div class="footer-social">
              <div class="footer-link footer-logo">
                <a href="https://metacpan.org/">
                  <img src="https://metacpan.org/static/images/metacpan-logo.svg" alt="MetaCPAN" />
                </a>
              </div>
              <a class="footer-social-link" href="https://github.com/metacpan">
                <i class="fab fa-github-square"></i>
              </a>
              <a class="footer-social-link" href="https://fosstodon.org/@metacpan">
                <i class="fab fa-mastodon"></i>
              </a>
            </div>
            <div class="footer-links">
              <div class="footer-link">
                  <a href="https://metacpan.org/about">About</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/about/sponsors">Sponsor</a>
              </div>
              <div class="footer-link">
                  <a href="https://grep.metacpan.org">grep::cpan</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/recent">Recent</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/about/faq">FAQ</a>
              </div>
              <div class="footer-link">
                  <a href="https://metacpan.org/tools">Tools</a>
              </div>
              <div class="footer-link">
                  <a href="https://fastapi.metacpan.org/">API</a>
              </div>
              <div class="footer-link">
                  <a href="https://www.perl.org/">Perl.org</a>
              </div>
            </div>
            <div class="footer-sponsors">
              <a class="footer-sponsor-link" target="_blank" href="https://www.bytemark.co.uk/" rel="noopener">
                <img class="footer-sponsor-bytemark" src="https://metacpan.org/static/images/sponsors/bytemark_logo.svg" alt="Bytemark logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://www.liquidweb.com/" rel="noopener">
                <img class="footer-sponsor-liquidweb" src="https://metacpan.org/static/images/sponsors/liquidweb_logo.png" alt="liquidweb logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://deriv.com/careers/" rel="noopener">
                <img class="footer-sponsor-deriv" src="https://metacpan.org/static/images/sponsors/deriv.svg" alt="Deriv logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://geocode.xyz" rel="noopener">
                <img class="footer-sponsor-geocode" src="https://metacpan.org/static/images/sponsors/geocodelogo.svg" alt="Geocode logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://www.fastly.com/" rel="noopener">
                <img class="footer-sponsor-fastly" src="https://metacpan.org/static/images/sponsors/fastly_logo.svg" alt="Fastly logo">
              </a>
              <a class="footer-sponsor-link" target="_blank" href="https://opencagedata.com" rel="noopener">
                <img class="footer-sponsor-opencage" src="https://metacpan.org/static/images/sponsors/open-cage.svg" alt="OpenCage logo">
              </a>
            </div>
          </div>
        </footer>
        <div class="modal fade" tabindex="-1" role="dialog" id="metacpan_keyboard-shortcuts">
          <div class="modal-dialog">
            <div class="modal-content">
              <div class="modal-header">
                <button type="button" class="close" data-dismiss="modal">&times;</button>
                <h4 class="modal-title">Keyboard Shortcuts</h4>
              </div>
              <div class="modal-body row">
<div class="col-md-6">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>Global</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>s</kbd>
        </td>
        <td>Focus search bar</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>?</kbd>
        </td>
        <td>Bring up this help dialog</td>
      </tr>
    </tbody>
  </table>

  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>GitHub</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>p</kbd>
        </td>
        <td>Go to pull requests</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>i</kbd>
        </td>
        <td>go to github issues (only if github is preferred repository)</td>
      </tr>
    </tbody>
  </table>
</div>

<div class="col-md-6">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>POD</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>a</kbd>
        </td>
        <td>Go to author</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>c</kbd>
        </td>
        <td>Go to changes</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>i</kbd>
        </td>
        <td>Go to issues</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>d</kbd>
        </td>
        <td>Go to dist</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>r</kbd>
        </td>
        <td>Go to repository/SCM</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>s</kbd>
        </td>
        <td>Go to source</td>
      </tr>
      <tr>
        <td class="keys">
          <kbd>g</kbd> <kbd>b</kbd>
        </td>
        <td>Go to file browse</td>
      </tr>

    </tbody>
  </table>
</div>

<div class="col-md-12">
  <table class="table keyboard-shortcuts">
    <thead>
      <tr>
        <th></th>
        <th>Search terms</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><em>module:</em> (e.g. <a href="https://metacpan.org/search?q=module%3APlugin">module:Plugin</a>)</td>
      </tr>
      <tr>
        <td><em>distribution:</em> (e.g. <a href="https://metacpan.org/search?q=distribution%3ADancer+auth">distribution:Dancer auth</a>)</td>
      </tr>
      <tr>
        <td><em>author:</em> (e.g. <a href="https://metacpan.org/search?q=author%3ASONGMU+Redis">author:SONGMU Redis</a>)</td>
      </tr>
      <tr>
        <td><em>version:</em> (e.g. <a href="https://metacpan.org/search?q=version%3A1.00">version:1.00</a>)</td>
      </tr>
    </tbody>
  </table>
</div>
              </div>
              <div class="modal-footer"></div>
            </div>
          </div>
        </div>
    </body>
</html>
